fix: instrument MCP List Tools spans in OpenAI Agents#4387
fix: instrument MCP List Tools spans in OpenAI Agents#4387hashwnath wants to merge 1 commit intoopen-telemetry:mainfrom
Conversation
Handle MCPListToolsSpanData so that MCP list_tools spans are properly instrumented with operation name "mcp.list_tools", SpanKind.CLIENT, and MCP-specific attributes (server name, tools count, tools list) instead of appearing as "unknown" spans with no data. Fixes open-telemetry#4197
|
|
|
@hashwnath thanks for the pr, in order to contribute to this project you need to sign the CLA |
MikeGoldsmith
left a comment
MikeGoldsmith
left a comment
There was a problem hiding this comment.
Thanks for the PR @hashwnath!
The implementation follows the existing patterns well. However, a concern before approving is that a number of attributes don't align with the MCP semantic conventions that are already in the Python semconv package (opentelemetry/semconv/_incubating/attributes/mcp_attributes.py).
mcp.server.name is not a semconv attribute
The registered MCP attributes are mcp.method.name, mcp.protocol.version, mcp.resource.uri, and mcp.session.id. There is no mcp.server.name. The MCP span spec uses server.address for server identity.
mcp.tools.count and mcp.tools.list are not in semconv
These are custom attributes with no semconv backing. We should not add non-spec attributes. You're welcome to open a semconv proposal to suggest them if you think they'd be valuable.
Span name and operation name should follow MCP semconv
Per the MCP span spec, span names should follow {mcp.method.name} {target}. For this span type the method name is tools/list (McpMethodNameValues.TOOLS_LIST), so the span name should be tools/list Time rather than mcp.list_tools Time. The mcp.method.name attribute should also be set on the span.
The GenAIOperationName.MCP_LIST_TOOLS = "mcp.list_tools" value also diverges from the rest of the class (all others use underscores, e.g. agent_handoff) and isn't a defined gen_ai.operation.name value in the GenAI semconv.
3 participants
Description
Fixes #4197
Problem: The OpenAI Agents SDK emits
MCPListToolsSpanDataspans when an agent fetches the list of tools from an MCP server, but the instrumentation did not handle this span data type. As a result, these spans appeared as"unknown"withoperation_name="unknown"and no useful attributes.Fix:
MCPListToolsSpanDatain both the direct and fallback import blocks"mcp.list_tools"SpanKind.CLIENT(outgoing call to MCP server)mcp.list_tools {server_name}format (e.g.,mcp.list_tools Time)mcp.server.name,mcp.tools.count, andmcp.tools.list(list only when content capture is enabled)Testing: Added unit test verifying operation name, span name, span kind, server attribute, and tools count for MCP list tools spans. All 104 existing tests continue to pass.
Note: A previous PR (#4285) attempted to fix this issue but was closed without merging. This PR takes a similar approach but integrates more completely with the existing patterns in the codebase, including proper span naming via
get_span_name(), output type inference, and attribute extraction through the standard_extract_genai_attributesdispatch.Type of Change